This tutorial will introduce you to a more in depth view of what FreeMarker templates are and how you can use the data provided to templates by GeoServer.

Freemarker

Freemarker is a simple yet powerful template engine that GeoServer uses whenever developer allowed user customization of outputs. In particular, at the time of writing it's used to allow customization of GetFeatureInfo, GeoRSS and KML outputs.

Freemarker allows for simple variable expansions, as in ${myVarName}, expansion of nested properties, such as in ${feature.myAtt.value}, up to little programs using loops, ifs and variables.
Most of the relevant information about how to approach template writing is included in the Freemarker's Designer guide and won't be repeated here: the guide, along with the KML and GetFeatureInfo template tutorials should be good enough to give you a good grip on how a template is built.

Template lookup

Geoserver looks up templates in three different places, allowing you for various level of customization. Given a templated output, a template name (template.ftl) and a feature type (myFeatureType), Geoserver will perform the following lookups:

• Look into GEOSERVER_DATA_DIR/featureTypes/myfeatureType/template.ftl to see if there is a type specific template
• Look into GEOSERVER_DATA_DIR/featureTypes/template.ftl looking for a global override
• Look into the GeoServer classpath and load the default template

Each templated output format tutorial should provide you with the template names, and state whether the templates can be type specific, or not.
Missing the source for the default template, look up for the service jar in the geoserver distribution (for example, wms-x.y.z.jar), unpack it, and you'll find the actual xxx.ftl files GeoServer is using as the default templates.

Common Data Models

Freemarker calls "data model" the set of data provided to the template. Each output format used by Geoserver will inject a different data model according to the informations it's managing, yet there are three very common elements that appear in almost each template, Feature, FeatureType and FeatureCollection. Here we provide a data model of each.

The data model is a sort of a tree, where each element has a name and a type. Besides basic types, we'll use:

• list: a flat list of items that you can scan thru using the FreeMarker <#list> directive;
• map: a key/value map, that you usually access using the dot notation, as in ${myMap.myKey}, and can be nested;
• listMap: a special construct that is, at the same time, a Map, and a list of the values.

Here are the three data models (as you can see there are redundancies, in particular in attributes, we chose this approach to make template building easier):

• FeatureType (map)
  • name (string): the type name
  • attributes (listMap): the type attributes
    • name (string): attribute name
    • type (string): attribute type, the fully qualified Java class name
    • isGeometry (boolean): true if the attribute is geometric, false otherwise
• Feature (map)
  • fid (string): the feature ID (WFS feature id)
  • typeName (string): the type name
  • attributes (listMap): the list of attributes (both data and metadata)
    • name (string): attribute name
    • type (string): attribute type, the fully qualified Java class name
    • isGeometry (boolean): true if the attribute is geometric, false otherwise
    • value: the attribute value (as a string)
• FeatureCollection (map)
  • features (list of Feature, see above)
  • type (FeatureType, see above)